Skip to Content

10. 从 MVP 到生产：架构蓝图、技术栈与落地清单

本章高频面试题

  1. 如果从 0 到 1 开发一个 Agent 系统，你会怎么分阶段推进？
  2. 技术栈如何选择，什么时候该用轻方案，什么时候该升级为复杂架构？
  3. 一个生产级 Agent 系统的最小可落地架构是什么？
  4. 2026 的 Agent 技术栈主流组件有哪些？Model Gateway / Vector DB / Durable Execution / Observability 各自推荐什么？
  5. 如何做评估、监控、回归和线上排障？
  6. 如何设计 guardrails、安全边界和人工审批？
  7. Agent runtime 为什么经常要独立服务部署？
  8. 成本工程怎么做？模型路由、prompt caching、trajectory 治理分别能省多少？
  9. 一个成熟 Agent 系统的常见失败模式有哪些？

1. 建设顺序：不要一上来就上复杂架构

很多团队一开始就想把多 agent、Kafka、图数据库、各种编排框架、花哨前端一次性全上。这通常不是最佳策略。

阶段一：验证任务闭环

目标：

  • 先证明这个任务真的需要 Agent（不是 workflow 能解决）
  • 先跑通一条最小闭环

这个阶段最需要：

  • 清晰的目标定义（含可度量成功标准）
  • 简单结构化 state
  • 基本工具调用
  • 最小评估集（10-30 条 golden）

阶段二：补可靠性

目标：

  • 失败恢复（checkpointer、idempotency key、retry with backoff）
  • Tracing（OTel + LangSmith/Langfuse）
  • 输入/输出 guardrails
  • 人工审批（高风险动作）
  • 上下文优化（compaction、prompt caching）

阶段三：补扩展性

目标：

  • 工具平台化（MCP 接入、工具权限分级、progressive disclosure）
  • 技能库治理（catalog + 按需加载 + 版本灰度）
  • 记忆层分层（短期 + 长期 + 遗忘策略）
  • 事件流和 UI（SSE + resumable + AG-UI 语义）
  • 更复杂的并发和长流程编排（durable execution 外挂）

2. 推荐的最小可落地架构（中小团队起点）

2.1 后端

  • Node.js + TypeScript（或 Python 生态对应的 FastAPI）
  • API server（NestJS / Next.js API routes / Fastify）
  • Agent runtime 层（LangGraph 或 LangChain createAgent）
  • 持久化数据库（Postgres）
  • 轻量消息/任务系统（Redis Streams、BullMQ）

2.2 Agent 层

  • 起步用 LangChain createAgent + middleware
  • 复杂编排（长任务、interrupt、多分支）升级到 LangGraph
  • 长时副作用（发布、爬取、多小时任务）外挂到 Temporal / Inngest / Restate

2.3 存储层

  • Postgres 承载：

    • run 状态、审批记录、事件表（outbox pattern）
    • 结构化业务数据
    • LangGraph checkpointer（@langchain/langgraph-checkpoint-postgres）
    • pgvector 扩展承载向量检索（中小规模够用）

  • 规模起来后再独立向量库：Qdrant / Weaviate / Pinecone

2.4 前端

  • Next.js + React（App Router）
  • SSE 优先；资源允许用 Vercel AI SDK 或 LangGraph useStream
  • 状态管理用 Zustand 或 Redux Toolkit

2.5 观测

  • OTel SDK（GenAI semantic conventions）
  • LangSmith 或 Langfuse 任选一个作为 LLM-specific tracing
  • 结构化日志（pino / winston）+ Loki / CloudWatch

3. 2026 的 Agent 技术栈主流组件

3.1 Model Gateway / Router

  • LiteLLM：开源、100+ provider、自托管友好
  • Portkey：托管 gateway + observability + guardrails 三合一
  • OpenRouter：多模型路由 + 统一计费
  • 自研：基于 OTel + 多 provider SDK

价值：

  • Provider 切换零改动
  • Fallback 和 retry 集中管理
  • Usage / cost 统一归因
  • Rate limit 统一观测

3.2 Agent Runtime

  • LangGraph（+ LangGraph Platform/Server）
  • LlamaIndex Workflows
  • CrewAI（多 agent 场景，生产使用需谨慎）
  • 自研 state machine（复杂业务、合规场景）

3.3 Durable Execution（长任务外挂）

  • Temporal：老牌、跨语言、最成熟
  • Inngest：TS 友好、serverless 原生、事件驱动
  • Restate：新秀，轻量低延迟
  • Trigger.dev：开发者体验好，TS 生态

3.4 Vector DB / Retrieval

  • pgvector（Postgres 扩展）：起步首选，HNSW 索引够用到百万级
  • Qdrant：开源 + 托管，支持 hybrid search 原生
  • Weaviate：hybrid + multi-tenancy 成熟
  • Pinecone：托管，规模大时省心
  • Turbopuffer：serverless 向量库，成本低
  • Elastic / OpenSearch：大规模企业已在用，直接扩展

Rerank：

  • Cohere Rerank v3、Voyage rerank：商业 API
  • BGE-reranker、Jina rerank：开源自托管

3.5 Tool / MCP

  • MCP (Model Context Protocol)：2025-06-18 规范是当前稳定版
  • MCP server 接入 + 内部 tool registry 并存
  • 重点关注供应链安全（见第 8 章）

3.6 Observability

  • LangSmith（托管，LangChain 深度集成）
  • Langfuse（开源 + 托管，provider 无关）
  • Phoenix (Arize)（开源，OTel 原生，evals 强）
  • Helicone（代理型，最低侵入）
  • 底层走 OpenTelemetry + GenAI semantic conventions

3.7 Evals

  • RAGAS（RAG 评估）
  • Promptfoo（prompt 回归测试）
  • DeepEval（Pytest 风格的 LLM eval）
  • LangSmith Evals / Phoenix Evals（和 tracing 一体）

3.8 前端

  • Vercel AI SDK（跨 provider，generative UI）
  • CopilotKit（嵌入式 copilot）
  • assistant-ui（可组合的聊天 UI 组件库）
  • LangGraph useStream（后端是 LangGraph 的首选）

4. 一个真正可落地的最小架构蓝图

4.1 前端层

  • Next.js + React
  • 聊天/任务页面
  • SSE 接收流式事件（带 Last-Event-ID 恢复）
  • 审批卡片和任务状态面板

4.2 API / BFF 层

  • 接收用户请求、认证、rate limit
  • 创建 run（写到 Postgres，返回 runId）
  • 暴露 SSE stream endpoint
  • 暴露 approve / reject / cancel / resume 接口
  • OTel trace 传播

4.3 Agent Runtime 层

  • LangGraph 承载主 agent
  • Checkpointer 到 Postgres
  • interrupt() 承载 HITL
  • 事件通过 outbox 写到 Redis Streams
  • 副作用动作（发邮件、publish）通过 message 到 Temporal/Inngest worker

4.4 Tool / Skill 层

  • 统一工具注册（自研 registry + MCP client）
  • Progressive disclosure（catalog + 按需加载）
  • 权限过滤、参数校验、风险分级
  • Skill 按 YAML frontmatter 管理，载入时校验

4.5 Retrieval / Memory 层

  • pgvector 做向量检索（或 Qdrant 独立）
  • Hybrid retrieval（向量 + BM25 via tsvector 或 Elastic）
  • Cohere/BGE rerank
  • Contextual retrieval 预处理
  • Short-term memory 在 LangGraph state 里
  • Long-term memory 在独立表（事实 / 情节 / 关系三类）

4.6 存储层

  • Postgres：runs、steps、events、approvals、prompt_versions、audit_logs、memory、vectors
  • Redis：事件流实时层、rate limit、session cache
  • 对象存储（S3/R2）：大文件、审批证据、trace 冷存档

4.7 观测层

  • OTel Collector（接 GenAI conventions）
  • LangSmith / Langfuse 作为 LLM-specific UI
  • Grafana / CloudWatch 作为通用 metrics/dashboards
  • Eval job（CI + 定时跑真实流量采样）

4.8 Model Gateway

  • LiteLLM 或自研 gateway 做多 provider 路由
  • Prompt caching 控制（Anthropic 显式标记、OpenAI 前缀稳定）
  • 成本归因（per workspace / per feature）
  • Fallback policies

理解关键：

最小蓝图不依赖”很多高级组件”，而是先把 Agent 的最关键能力闭环起来：状态、工具、检索、事件、审批、恢复、观测、成本。

5. Agent Runtime 为什么经常要独立服务

几个务实原因：

  1. 请求生命周期长：Agent run 可能跑几分钟到几小时，和普通 HTTP handler 的 30s 超时模式不匹配
  2. SSE 和长连接：需要长时间保持连接，轻量 serverless 不友好
  3. Checkpoint 持久化：状态必须能跨进程/机器恢复
  4. Worker pool 模型：后台执行 interrupt resume、schedule run、long task
  5. 独立扩容：agent 的负载特征和 API 不一样，独立伸缩更合理

实现路径：

  • LangGraph Server / LangGraph Platform（最省事）
  • 自建 Node/Python 服务 + Redis/Postgres + 守护进程
  • 副作用单独走 Temporal/Inngest worker

6. 成本工程：Agent 最容易失控的维度

Agent 的经济学问题：token × 步数 × 模型价格 × 用户数。不做治理很快就失控。

6.1 模型路由

  • 简单意图分类/摘要用 Haiku 级（Claude Haiku 4.5、GPT-5 nano 级别）
  • 规划/工具选择用 Sonnet 级
  • 复杂推理/决策用 Opus 级
  • 单次节省可达 10-100x

6.2 Prompt Caching

  • Anthropic cache read = 0.1x base（节省 90%）
  • OpenAI 自动 prefix caching 类似
  • 前提是前缀稳定（见第 3 章）
  • 监控 cache hit rate，<50% 就是架构问题

6.3 Trajectory 治理

  • Deep Agents 模式减少主 context 膨胀
  • Sub-agent 隔离大量中间推理
  • 工具返回值的 context budget 硬上限
  • Circuit breaker 限制步数/token/成本

6.4 批处理

  • 离线任务用 Batch API（Anthropic、OpenAI 都有，50% 折扣）
  • 非实时的 embed、summary、classification 都走 batch

6.5 自研 fallback

  • Opus 失败自动降级到 Sonnet（用 LangChain .withFallbacks() 或 gateway）
  • 长对话自动触发 compaction
  • 超预算自动降级到”只给建议不执行”模式

7. 技术栈选择的判断原则

7.1 先按复杂度选，不按潮流选

单 Agent + 少量工具 + 单向流式聊天： Next.js + Node.js + SSE + Postgres + pgvector 就够用。

7.2 何时考虑更复杂基础设施

出现这些需求时再升级：

  • 多消费者事件系统
  • 复杂异步任务（分钟到小时）
  • 大规模并发（万级 concurrent run）
  • 高强度回放和分析
  • 跨服务事件处理
  • 合规审计

这时才值得考虑：

  • Kafka / Redpanda 替代 Redis Streams
  • 独立 vector DB（Qdrant / Pinecone）
  • Temporal / Inngest 承载长任务
  • 独立 Clickhouse / BigQuery 做 analytics

7.3 不要二次造轮子的地方

  • Checkpointer：用 LangGraph 自带的，不要自己写
  • SSE resumable stream：用 Vercel Resumable Streams 或 Redis Streams + Last-Event-ID
  • OTel 打点：用社区 instrumentation，不要自研
  • Structured output：用 provider 的 strict schema，不要自己做解析

7.4 值得自研的地方

  • Tool registry / skill catalog（业务强相关）
  • Permission / policy 规则（合规相关）
  • Domain-specific guardrails（行业相关）
  • Business-level evals（唯一了解业务的是自己）

8. 评估体系怎么做

生产级 Agent 至少三类评估：

8.1 离线评估（CI）

  • Gold set + adversarial set + 回归集
  • Prompt/model/skill 变更必跑
  • 阈值不达标阻塞合并
  • 历史趋势长期跟踪

8.2 在线监控

  • 任务成功率、时延、成本、trajectory 长度
  • Per-workspace / per-feature 的分布
  • Feedback（thumbs up/down、人工修正）回流
  • Canary 对比（shadow mode 指标）

8.3 人工评审

  • 高风险任务 / 关键样本 / 新功能的首批真实流量
  • 用于校准 LLM-as-judge 的判断
  • 发现自动指标抓不到的问题

9. 线上排障的最小要求

任何复杂 Agent，上线后想排障至少需要：

  • run_id / thread_id / trace_id
  • 当前 prompt_version / model_version / skill_version
  • 完整的 tool call trail（name、args、result、latency、error）
  • 检索召回结果（chunk ids + scores）
  • State snapshot 在关键节点
  • 最终输出
  • 错误堆栈和错误码
  • 对应的 OTel span 链路

没有这些信息，线上问题根本无法定位。

10. 常见失败模式

10.1 工具误调用

表现：选错工具、参数填错、明明该检索却直接回答

治理：

  • description + 正向/负向约束（软）
  • Progressive disclosure（减少工具集）
  • 动态 tool filtering（硬）
  • Tool verifier / LLM-as-judge
  • Specificity 指标监控

10.2 上下文污染 / 漂移

表现：模型被旧信息干扰、目标偏移、长对话后质量下降

治理：

  • 定期 compaction
  • Scratchpad offload
  • Semantic checkpoint
  • 分层上下文
  • Progress assessment + replan

10.3 RAG 召回错

表现：明明知识库里有答案却没找到、找到的是不相关文档

治理：

  • 改 chunking
  • Hybrid retrieval + RRF
  • Contextual retrieval
  • Rerank
  • Metadata filter
  • RAGAS 评估

10.4 长任务不可恢复

表现：中途失败后整个 run 作废、用户刷新后上下文丢失、进程重启丢状态

治理：

  • LangGraph checkpointer
  • Durable execution 外挂
  • Event store + outbox
  • SSE resumable stream
  • Idempotency key

10.5 无限循环 / 成本失控

表现：agent 卡在重复调用同一工具、单次 run 花费超千元

治理：

  • Multi-layer circuit breaker（步数/token/成本/wall-clock）
  • 同 tool 调用次数限制
  • Progress assessment
  • Deadlock detection

10.6 Prompt Injection 中招

表现：agent 按外部内容的”指令”行事、泄露内部数据、调用未授权工具

治理：

  • Tool visibility filtering
  • Dual-LLM pattern
  • Input sanitization + 分类器
  • HITL 兜底高风险
  • OWASP LLM Top 10 合规

10.7 模型升级导致质量回退

表现：provider 发新版本、换了 default model ID，效果变差

治理：

  • 固定 model ID（claude-opus-4-7，不用 claude-opus-latest）
  • Shadow mode 灰度
  • Regression eval on CI
  • 自动回滚

11. 给初学者的工程落地 checklist

任务定义

  • 任务目标清楚吗（可度量）
  • 成功标准清楚吗
  • 什么必须人工确认
  • 什么可以自动执行
  • Autonomy level 定义好了吗

模型与 Prompt

  • 模型是否适合这个任务（能力 / 延迟 / 成本）
  • Prompt 是否分层（system / developer / user）
  • Prompt 是否版本化
  • 是否有基本 eval
  • Prompt cache 架构友好吗（前缀稳定、动态后置）

Context

  • 当前任务状态是否结构化
  • 历史消息如何裁剪（compaction 策略）
  • 检索结果如何注入
  • 权限信息是否显式传入
  • 超长上下文的 scratchpad offload 设计

Tools

  • 工具是否单一职责
  • Schema 是否清晰（含正向/负向约束）
  • 高风险工具是否分级
  • Progressive disclosure 架构了吗
  • 错误返回是否”可操作”（retryable / hint / code）
  • 写操作是否有 idempotency key
  • MCP 接入是否做了供应链审查

Skills

  • 哪些流程值得封装成 skill
  • Skill 是否有完整元数据（owner、lastEvaluatedAt）
  • 是否有 catalog + 按需加载
  • 是否有版本治理和灰度机制

Memory 与 RAG

  • 短期和长期记忆是否分开
  • RAG 是否有 baseline
  • 是否规划了 hybrid + rerank + contextual retrieval
  • Chunk metadata 是否完整
  • 多租户隔离在存储层强制了吗
  • 写入门槛和遗忘策略设计好了吗

Runtime 与事件流

  • Run 是否有 checkpoint（可恢复）
  • 事件是否可排序、去重、回放
  • 是否支持 interrupt / resume
  • SSE stream 是否 resumable（Last-Event-ID）
  • UI 是否能区分阶段和终态
  • Circuit breaker 层次（步数/token/成本/工具调用次数）

观测与安全

  • OTel GenAI conventions 打点了吗
  • 关键指标有 dashboard 吗（成功率 / p95 / 成本 / trajectory / cache hit）
  • 失败样本有留存吗
  • 权限和审批在系统层强制了吗
  • 高风险审计完整吗
  • OWASP LLM Top 10 评估过了吗
  • Indirect prompt injection 防御做了吗

成本

  • 模型路由设计了吗（Haiku / Sonnet / Opus 分层）
  • Prompt caching 配置了吗
  • Trajectory / token / 成本有 budget 和 circuit breaker 吗
  • 批处理场景走 Batch API 了吗

12. 最后给你的总方法论

如果你只记一段话，我建议记下面这段：

设计 Agent 系统时，我会先确认问题是否真的需要 Agent——能用 workflow 解决的就不上 agent。然后把系统拆成确定性和不确定性两部分：确定性交给状态机、工作流、规则和 server-side 校验，不确定性交给模型。我会优先设计 state、tools、context、memory、RAG、事件流和 checkpoint 机制，而不是只写 Prompt。Agent runtime 从第一天就用 LangGraph（或等价 durable execution），前端走 SSE + resumable stream + AG-UI 事件语义。权限和审批必须由系统硬执行，工具可见性动态裁剪，高风险走 HITL。观测层走 OpenTelemetry GenAI conventions 叠加 LangSmith/Langfuse/Phoenix。成本工程用模型路由 + prompt caching + circuit breaker。Prompt / model / skill / tool 任何变更都必须过 eval 回归，shadow → canary → 全量发布。生产级 Agent 的核心不是一次跑通，而是可恢复、可观察、可评估、可演进、可合规、可控成本。

Last updated on
从 Copilot 到 Agent